Article Unit Barcodes

Frequency:

Article unit barcode master data changes are required to be sent in near real-time. Any change to an interface field in the external system should trigger the interface.

Expected data:

Article unit barcodes for different levels of the article package hierarchy.

Multiple barcodes can be attached to any article unit level.

All article unit barcodes for an article are expected in a single message.

Technical:

The article must already exist in DSMDS.

The barcodes in the message replace all existing barcodes of the article in DSMDS: new barcodes are created, and barcodes that are not in the message are deleted.

If any unit or barcode of an article produces a warning, the existing barcodes of that article are left unchanged. The other articles in the request are still processed.

An article unit of the given unit type does not need to exist in DSMDS.

units and each unit's barcodes must be present; a missing or null value fails the request with 409. "units": [] removes all barcodes of the article, and "barcodes": [] adds no barcodes for that unit.

Barcodes are stored as sent; duplicate barcodes are not removed.

The request is processed in a single transaction. If a barcode cannot be saved (e.g., it is longer than 255 characters), the request fails with 409 and no barcodes from the request are changed.

---

POST https://{url}/articles/units/barcodes/v1

Replace article unit barcodes.

Request Body

The request body is a JSON array of objects. Each object contains an article_id and a units array. Each unit contains a unit_type_id and a barcodes array.

Top-level object:

Name	Type	Required	Description
article_id	string	Yes	Article unique identifier in the external system
units	array	Yes	Array of unit objects for the article. Must not be null. An empty array removes all barcodes of the article

Unit object (inside units array):

Name	Type	Required	Description
unit_type_id	integer	Yes	Unit type: 1 - base unit, 2 - warehouse unit, 3 - layer unit, 4 - pallet unit
barcodes	array	Yes	Array of barcode objects for the unit. Must not be null. An empty array adds no barcodes for the unit

Barcode object (inside barcodes array):

Name	Type	Required	Description
barcode	string	Yes	Barcode value. Must not be empty. Max 255 characters
barcode_type_id	string	No	Barcode type: EAN128, EAN13 or EAN14. Matched exactly (case-sensitive). Any other or missing value is stored as UNKNOWN, without a warning

Request Example

[
    {
        "article_id": "0001",
        "units": [
            {
                "unit_type_id": 1,
                "barcodes": [
                    {
                        "barcode_type_id": "EAN13",
                        "barcode": "4013853567222"
                    },
                    {
                        "barcode_type_id": "EAN13",
                        "barcode": "4012918688192"
                    }
                ]
            },
            {
                "unit_type_id": 2,
                "barcodes": [
                    {
                        "barcode_type_id": "EAN14",
                        "barcode": "15012345678907"
                    }
                ]
            }
        ]
    }
]

Response

200: OK — Success

{
    "success": true,
    "message": "",
    "data": null,
    "warnings": []
}

200: OK — Success with warnings

{
    "success": true,
    "message": null,
    "data": null,
    "warnings": [
        "Article not found by ID '0001' for client: 20",
        "Article unit barcodes not imported, articleId is empty",
        "Article '0047' unit barcodes were not imported for article unit type '5', specified article unit type was not found for client '20'",
        "barcode is empty for article '0048', unit type '1"
    ]
}

200: OK — Error

{
    "success": false,
    "message": "Failed to map JSON",
    "data": null,
    "warnings": []
}